.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 1980 Regents of the University of California.
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH CTAGS 1HAS "Mar 18, 1997"
.SH NAME
ctags \- create a tags file for use with ex and vi
.SH SYNOPSIS
.nf
\fB/usr/bin/ctags\fR [\fB-aBFtuvwx\fR] [\fB-f\fR \fItagsfile\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ctags\fR [\fB-aBFuvwx\fR] [\fB-f\fR \fItagsfile\fR] \fIfile\fR...
.fi

.SH DESCRIPTION
The \fBctags\fR utility makes a tags file for \fBex\fR(1) from the specified C,
C++, Pascal, FORTRAN, \fByacc\fR(1), and  \fBlex\fR(1) sources. A tags file
gives the locations of specified objects (in this case functions and typedefs)
in a group of files.  Each line of the tags file contains the object name, the
file in which it is defined, and an address specification for the object
definition. Functions are searched with a pattern, typedefs with a line number.
Specifiers are given in separate fields on the line, separated by SPACE or TAB
characters. Using the tags file, \fBex\fR can quickly find these objects'
definitions.
.LP
Normally,  \fBctags\fR places the tag descriptions in a file called \fBtags\fR;
this may be overridden with the \fB-f\fR option.
.LP
Files with names ending in \fB\&.c\fR or \fB\&.h\fR are assumed to be either C
or C++ source files and are searched for C/C++  routine and macro definitions.
Files with names ending in \fB\&.cc\fR, \fB\&.C\fR, or \fB\&.cxx\fR are
assumed to be C++ source files. Files with names ending in \fB\&.y\fR are
assumed to be  \fByacc\fR source files. Files with names ending in \fB\&.l\fR
are assumed to be  \fBlex\fR files.  Others are first examined to see if they
contain any Pascal or \fBFORTRAN\fR routine definitions; if not, they are
processed again looking for C  definitions.
.LP
The tag \fBmain\fR is treated specially in C or C++ programs.  The tag formed
is created by prepending \fBM\fR to \fIfile\fR, with a trailing \fB\&.c\fR,
\fB\&.cc\fR, \fB\&.C\fR, or \fB\&.cxx\fR removed, if any, and leading path
name components also removed.  This makes use of \fBctags\fR practical in
directories with more than one program.
.SH OPTIONS
The precedence of the options that pertain to printing is \fB-x\fR, \fB-v\fR,
then the remaining options. The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 15n
Appends output to an existing \fBtags\fR file.
.RE

.sp
.ne 2
.na
\fB\fB-B\fR\fR
.ad
.RS 15n
Uses backward searching patterns (\fB?\fR.\|.\|.\|\fB?\fR).
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fItagsfile\fR\fR
.ad
.RS 15n
Places the tag descriptions in a file called \fItagsfile\fR instead of
\fBtags\fR.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 15n
Uses forward searching patterns (\fB/\fR.\|.\|.\|\fB/\fR) (default).
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 15n
Creates tags for typedefs. \fB/usr/xpg4/bin/ctags\fR creates tags for typedefs
by default.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 15n
Updates the specified files in tags, that is, all references to them are
deleted, and the new values are appended to the file. Beware: this option is
implemented in a way that is rather slow; it is usually faster to simply
rebuild the \fBtags\fR file.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 15n
Produces on the standard output an index listing the function name, file name,
and page number (assuming 64 line pages). Since the output will be sorted into
lexicographic order, it may be desired to run the output through \fBsort\fR
\fB-f\fR.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 15n
Suppresses warning diagnostics.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 15n
Produces a list of object names, the line number and file name on which each is
defined, as well as the text of that line and prints this on the standard
output. This is a simple index which can be printed out as an off-line readable
function index.
.RE

.SH OPERANDS
The following \fIfile\fR operands are supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fB\&.c\fR\fR
.ad
.RS 12n
Files with basenames ending with the \fB\&.c\fR suffix are treated as
C-language source code.
.RE

.sp
.ne 2
.na
\fB\fIfile\fR\fB\&.h\fR\fR
.ad
.RS 12n
Files with basenames ending with the \fB\&.h\fR suffix are treated as
C-language source code.
.RE

.sp
.ne 2
.na
\fB\fIfile\fR\fB\&.f\fR\fR
.ad
.RS 12n
Files with basenames ending with the \fB\&.f\fR suffix are treated as
FORTRAN-language source code.
.RE

.SH USAGE
The \fB-v\fR option is mainly used with \fBvgrind\fR which will be part of the
optional \fBBSD\fR Compatibility Package.
.SH EXAMPLES
\fBExample 1 \fRProducing entries in alphabetical order
.LP
Using \fBctags\fR with the \fB-v\fR option produces entries in an order which
may not always be appropriate for \fBvgrind\fR. To produce results in
alphabetical order, you may want to run the output through \fBsort\fR \fB-f\fR.

.sp
.in +2
.nf
example% \fBctags -v filename.c filename.h | sort -f \|>\| index\fR
example% \fBvgrind -x index\fR
.fi
.in -2

.LP
\fBExample 2 \fRBuilding a tags file
.LP
To build a tags file for C sources in a directory hierarchy rooted at
\fIsourcedir\fR, first create an empty tags file, and then run  \fBfind\fR(1)

.sp
.in +2
.nf
example% \fBcd \fIsourcedir \fR ; rm -f tags ; touch tags\fR
example% \fBfind . \e( -name SCCS -prune -name \e\e
       '*.c' -o -name '*.h' \e) -exec ctags -u {} \e;\fR
.fi
.in -2

.LP
Notice that spaces must be entered exactly as shown.

.SH ENVIRONMENT VARIABLES
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of \fBctags\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.ne 2
.na
\fB\fBtags\fR\fR
.ad
.RS 8n
output tags file
.RE

.SH ATTRIBUTES
.SS "/usr/xpg4/bin/ctags"
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.BR ex (1),
.BR lex (1),
.BR vgrind (1),
.BR vi (1),
.BR yacc (1),
.BR attributes (7),
.BR environ (7),
.BR standards (7)
.SH NOTES
Recognition of \fBfunctions\fR, \fBsubroutines\fR, and \fBprocedures\fR for
\fBFORTRAN\fR and Pascal is done in a very simpleminded way. No attempt is made
to deal with block structure; if you have two Pascal procedures in different
blocks with the same name, you lose.
.LP
The method of deciding whether to look for C or Pascal and \fBFORTRAN\fR
functions is a hack.
.LP
The \fBctags\fR utility does not know about \fB#ifdefs\fR.
.LP
The \fBctags\fR utility should know about Pascal types. Relies on the input
being well formed to detect typedefs. Use of \fB-tx\fR shows only the last line
of typedefs.
